HistoryQuery Methods

The HistoryQuery object contains the following methods:

CancelHistoryFiltering
CreateHistoryFilter
GetHistoryEntriesWithinWindow
GetHistoryEntryAsXml
GetHistoryEntryFromWindowAsXml
IsHistoryFilterRunning
StartHistoryFiltering

Note: Some of the examples in this topic use the WScript.Sleep statement, which is not available for use when scripting in CygNet Studio. Use TheView's EventTimer instead.

CancelHistoryFiltering

The CancelHistoryFiltering method cancels the filtering of history.

Syntax

CancelHistoryFiltering(TimeToWaitInSeconds As Integer)

Parameters

Parameter	Required	Description
TimeToWaitInSeconds	Yes	The number of seconds to wait for the history query to terminate. This value must be within the range [1 - 100].

Example

The following example cleans up the query after it is finished, by clearing the results, canceling the filtering, and destroying the filter.

Copy

CancelHistoryFiltering

1
2
3
4
5
6
Sub
 
    ' history query is finished
    HistoryQuery.CancelHistoryFiltering()
 
End Sub

CreateHistoryFilter

The CreateHistoryFilter method creates a new history filter thread.

Syntax

CreateHistoryFilter() As Boolean

Example

The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.

Copy

CreateHistoryFilter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Sub
 
    '-----------------SETUP------------------ 
     
    ' create the filter
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    ' check that the filter thread is running
    Dim bIsRunning
    bIsRunning = HistoryQuery.IsHistoryFilterRunning()
     
    '-----------------EXECUTION------------------
     
    ' start filtering
    HistoryQuery.StartHistoryFiltering()
     
    ' wait for the thread to obtain history entries
    WScript.Sleep(1000)
     
    Dim strTag
    strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
     
    Dim MyDateS
    MyDateS = "1/7/2023"
    Dim startDate
    startDate = CDate(MyDateS)
    Dim MyDateE
    MyDateE = "6/4/2023"
    Dim endDate
    endDate = CDate(MyDateE) 
     
    ' retrieve a single history entry
    Dim pvHistoryInfoXml, bEntryRetrieved
    pvHistoryInfoXml = ""
    bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml)
    MsgBox pvHistoryInfoXml
     
    ' populate the internal set of entries for a given time window
    Dim nSize, bWindowRetrieved
    nSize = 0
    bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
     
    ' iterate through the set and retrieve each individual entry
    Dim iEntry
    For iEntry = 1 To nSize 
        pvHistoryInfoXml = ""
        bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml)
        If bEntryRetrieved Then
            MsgBox pvHistoryInfoXml
        End if
    Next
     
    '-----------------RESULTS------------------
     
    ' cancel the filtering, and wait 5 seconds for the thread to terminate
    HistoryQuery.CancelHistoryFiltering(5)
 
End Sub

GetHistoryEntriesWithinWindow

The GetHistoryEntriesWithinWindow method retrieves all of the filtered history entries for the specified tag within the specified time window.

Syntax

GetHistoryEntriesWithinWindow(Tag as String, StartTime As Date, EndTime As Date, Size As Integer) As Boolean

Parameters

Parameter	Required	Description
Tag	Yes	The point tag for the history entries to be retrieved.
StartTime	Yes	The earliest date/time of history entries to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function.
EndTime	Yes	The latest date/time of history entries to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function.
Size	Yes	The size of the list of history entries returned by this method.

Remark

This method does not actually return a set of history entries. Rather, it populates an internal set of history entries, which can be accessed via GetHistoryEntryFromWindowAsXml.

Example

The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.

Copy

GetHistoryEntriesWithinWindow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Sub
 
    '-----------------SETUP------------------ 
     
    ' create the filter
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    ' check that the filter thread is running
    Dim bIsRunning
    bIsRunning = HistoryQuery.IsHistoryFilterRunning()
     
    '-----------------EXECUTION------------------
     
    ' start filtering
    HistoryQuery.StartHistoryFiltering()
     
    ' wait for the thread to obtain history entries
    WScript.Sleep(1000)
     
    Dim strTag
    strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
     
    Dim MyDateS
    MyDateS = "1/7/2023"
    Dim startDate
    startDate = CDate(MyDateS)
    Dim MyDateE
    MyDateE = "6/4/2023"
    Dim endDate
    endDate = CDate(MyDateE) 
     
    ' retrieve a single history entry
    Dim pvHistoryInfoXml, bEntryRetrieved
    pvHistoryInfoXml = ""
    bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml)
    MsgBox pvHistoryInfoXml
     
    ' populate the internal set of entries for a given time window
    Dim nSize, bWindowRetrieved
    nSize = 0
    bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
     
    ' iterate through the set and retrieve each individual entry
    Dim iEntry
    For iEntry = 1 To nSize 
        pvHistoryInfoXml = ""
        bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml)
        If bEntryRetrieved Then
            MsgBox pvHistoryInfoXml
        End if
    Next
     
    '-----------------RESULTS------------------
     
    ' cancel the filtering, and wait 5 seconds for the thread to terminate
    HistoryQuery.CancelHistoryFiltering(5)
 
End Sub

GetHistoryEntryAsXml

The GetHistoryEntryAsXml method retrieves a single history entry for the specific tag and date.

Syntax

GetHistoryEntryAsXml(Tag as String, StartTime As Date, HistoryInfoXml As Variant) As Boolean

Parameters

Parameter	Required	Description
Tag	Yes	The point tag for the history entries to be retrieved.
StartTime	Yes	The date/time of the history entry to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function.
HistoryInfoXml	Yes	The XML representation of the history entry returned by this method.

Example

The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.

Copy

GetHistoryEntryAsXml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Sub
 
    '-----------------SETUP------------------ 
     
    ' create the filter
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    ' check that the filter thread is running
    Dim bIsRunning
    bIsRunning = HistoryQuery.IsHistoryFilterRunning()
     
    '-----------------EXECUTION------------------
     
    ' start filtering
    HistoryQuery.StartHistoryFiltering()
     
    ' wait for the thread to obtain history entries
    WScript.Sleep(1000)
     
    Dim strTag
    strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
     
    Dim MyDateS
    MyDateS = "1/7/2023"
    Dim startDate
    startDate = CDate(MyDateS)
    Dim MyDateE
    MyDateE = "6/4/2023"
    Dim endDate
    endDate = CDate(MyDateE) 
     
    ' retrieve a single history entry
    Dim pvHistoryInfoXml, bEntryRetrieved
    pvHistoryInfoXml = ""
    bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml)
    MsgBox pvHistoryInfoXml
     
    ' populate the internal set of entries for a given time window
    Dim nSize, bWindowRetrieved
    nSize = 0
    bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
     
    ' iterate through the set and retrieve each individual entry
    Dim iEntry
    For iEntry = 1 To nSize 
        pvHistoryInfoXml = ""
        bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml)
        If bEntryRetrieved Then
            MsgBox pvHistoryInfoXml
        End if
    Next
     
    '-----------------RESULTS------------------
     
    ' cancel the filtering, and wait 5 seconds for the thread to terminate
    HistoryQuery.CancelHistoryFiltering(5)
 
End Sub

GetHistoryEntryFromWindowAsXml

The GetHistoryEntryFromWindowAsXml method retrieves a history entry from the set of entries populated by GetHistoryEntriesWithinWindow.

Syntax

GetHistoryEntryFromWindowAsXml(EntryNumber As Integer, HistoryInfoXml As Variant) As Boolean

Parameters

Parameter	Required	Description
EntryNumber	Yes	The index of a history entry in the set populated by GetHistoryEntriesWithinWindow.
HistoryInfoXml	Yes	The XML representation of the history entry returned by this method.

Remark

This method is designed to be used in conjunction with GetHistoryEntriesWithinWindow, which populates an internal set of history entries, from which one can be retrieved using GetHistoryEntryFromWindowAsXml (this method).

Example

The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.

Copy

GetHistoryEntryFromWindowAsXml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Sub
 
    '-----------------SETUP------------------ 
     
    ' create the filter
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    ' check that the filter thread is running
    Dim bIsRunning
    bIsRunning = HistoryQuery.IsHistoryFilterRunning()
     
    '-----------------EXECUTION------------------
     
    ' start filtering
    HistoryQuery.StartHistoryFiltering()
     
    ' wait for the thread to obtain history entries
    WScript.Sleep(1000)
     
    Dim strTag
    strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
     
    Dim MyDateS
    MyDateS = "1/7/2023"
    Dim startDate
    startDate = CDate(MyDateS)
    Dim MyDateE
    MyDateE = "6/4/2023"
    Dim endDate
    endDate = CDate(MyDateE) 
     
    ' retrieve a single history entry
    Dim pvHistoryInfoXml, bEntryRetrieved
    pvHistoryInfoXml = ""
    bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml)
    MsgBox pvHistoryInfoXml
     
    ' populate the internal set of entries for a given time window
    Dim nSize, bWindowRetrieved
    nSize = 0
    bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
     
    ' iterate through the set and retrieve each individual entry
    Dim iEntry
    For iEntry = 1 To nSize 
        pvHistoryInfoXml = ""
        bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml)
        If bEntryRetrieved Then
            MsgBox pvHistoryInfoXml
        End if
    Next
     
    '-----------------RESULTS------------------
     
    ' cancel the filtering, and wait 5 seconds for the thread to terminate
    HistoryQuery.CancelHistoryFiltering(5)
 
End Sub

IsHistoryFilterRunning

The IsHistoryFilterRunning method returns true if the history query thread is running.

Syntax

IsHistoryFilterRunning() As Boolean

Remark

The history query thread is executed after a history filter is created; therefore, after a history filter is created, this method will only return false if the filter has been destroyed using CancelHistoryFiltering. Note that this method is checking that the thread is running, not that it is actually performing filtering.

Example

The following example creates a history filter, checks that it is running, cancels it, and checks that it is no longer running.

Copy

IsHistoryFilterRunning

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Sub
 
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    Dim bRunning
    bRunning = HistoryQuery.IsHistoryFilterRunning()
     
    MsgBox bRunning 'should be "True"
     
    HistoryQuery.CancelHistoryFiltering(100)
     
    bRunning = HistoryQuery.IsHistoryFilterRunning()
     
    MsgBox bRunning 'should be "False"
 
End Sub

StartHistoryFiltering

The StartHistoryFiltering method initiates history filtering on the background thread.

Syntax

StartHistoryFiltering() As Boolean

Remark

This method returns false if no history filter has been created.

Example

The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.

Copy

StartHistoryFiltering

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Sub
 
    '-----------------SETUP------------------ 
     
    ' create the filter
    Dim bCreatedOk
    bCreatedOk = HistoryQuery.CreateHistoryFilter()
     
    ' check that the filter thread is running
    Dim bIsRunning
    bIsRunning = HistoryQuery.IsHistoryFilterRunning()
     
    '-----------------EXECUTION------------------
     
    ' start filtering
    HistoryQuery.StartHistoryFiltering()
     
    ' wait for the thread to obtain history entries
    WScript.Sleep(1000)
     
    Dim strTag
    strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
     
    Dim MyDateS
    MyDateS = "1/7/2023"
    Dim startDate
    startDate = CDate(MyDateS)
    Dim MyDateE
    MyDateE = "6/4/2023"
    Dim endDate
    endDate = CDate(MyDateE) 
     
    ' retrieve a single history entry
    Dim pvHistoryInfoXml, bEntryRetrieved
    pvHistoryInfoXml = ""
    bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml)
    MsgBox pvHistoryInfoXml
     
    ' populate the internal set of entries for a given time window
    Dim nSize, bWindowRetrieved
    nSize = 0
    bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
     
    ' iterate through the set and retrieve each individual entry
    Dim iEntry
    For iEntry = 1 To nSize 
        pvHistoryInfoXml = ""
        bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml)
        If bEntryRetrieved Then
            MsgBox pvHistoryInfoXml
        End if
    Next
     
    '-----------------RESULTS------------------
     
    ' cancel the filtering, and wait 5 seconds for the thread to terminate
    HistoryQuery.CancelHistoryFiltering(5)
 
End Sub